Add Vivado xsim DPI-C co-simulation backend for RogueTcpStream, RogueTcpMemory, and RogueSideBand by ruck314 · Pull Request #1452 · slaclab/surf

ruck314 · 2026-07-07T05:24:15Z

Description

Adds a Vivado xsim/SystemVerilog DPI-C co-simulation backend for RogueTcpStream, RogueTcpMemory, and RogueSideBand alongside the existing GHDL/VHPIDIRECT and VCS/VHPI paths. The VHDL forwarding entities, SystemVerilog DPI leaves, and C adapters reuse the shared axi/simlink/shared/*Core.h ZeroMQ models and link into one RogueTcpDpi.so built by xsc.

Each elaborated model now owns an independent DPI chandle, native model state, ZeroMQ context, and two-port endpoint pair. Explicit create/update/destroy APIs, normal/fallback cleanup, cross-model port collision checks, and multi-instance regressions support established multi-link users without changing the public VHDL interfaces or Rogue TCP wire formats.

The xsim usage guide now references only checked-in examples and documents the clock/reset, unique-port, peer, and connected-and-draining transport requirements for external targets.

Details

This pull request is stacked on #1450 because it uses that pull request's backend split and shared C cores. It does not depend on #1450's later GHDL integer-handle implementation; after #1450 merges, this pull request can be retargeted to pre-release and any real integration conflicts resolved then.

The shared cores retain the established synchronous ZeroMQ send behavior used by VCS/VHPI and GHDL/VHPIDIRECT. Peers must be connected and draining before HDL produces outbound traffic. No-peer, saturation, linger, retry-queue, and worker-thread hardening is intentionally deferred to a separate cross-backend change so xsim does not acquire different transport semantics.

Validation:

The original backend was exercised end-to-end with Vivado 2025.2 and the rogue_v6.13.0 environment; the Stream PRBS loopback reported rxCount == 10 and rxErrors == 0.
The new host-native DPI adapter regression passes four tests, including four Stream, two Memory, and two SideBand contexts exchanging isolated tagged ZeroMQ traffic, lifecycle reuse, and negative ownership/port cases.
The checked-in Vivado regression elaborates the same eight-instance VHDL/SV topology, pulses reset twice, rejects duplicate port pairs, and compiles the C adapters against an xelab -dpiheader generated ABI. It skips explicitly when Vivado tools are unavailable; the new multi-instance xsim flow still needs a recorded Vivado-enabled run before merge.
Warning-enabled C compilation, Python lint, VSG, direct GHDL analysis of the xsim VHDL harness, and git diff --check pass locally.

Pairs with the ruckus-side xsc / -sv_lib RogueTcpDpi orchestration in slaclab/ruckus#399.

Add a third axi/simlink/ co-simulation backend -- Vivado xsim via SystemVerilog DPI-C -- alongside the existing GHDL (VHPIDIRECT) and VCS (VHPI) paths. A forwarding VHDL entity -> SV DPI leaf -> C adapter chain implements RogueTcpStream, RogueTcpMemory, and RogueSideBand, reusing the shared axi/simlink/shared/*Core.h ZeroMQ cores unchanged. All three link into one combined RogueTcpDpi.so via xsc. Additive only -- the GHDL/VCS backends and the cocotb regression are untouched. axi/simlink/ruckus.tcl selects the backend from RUCKUS_SIM_BACKEND (set by the ruckus make target: make xsim/gui -> xsim, make vcs -> vcs), falling back to GHDLFLAGS/VCS_VERSION sniffing for older ruckus. Sniffing VCS_VERSION alone is unreliable because users commonly source both Vivado and VCS in one setup script, which would otherwise load the vcs/ VHPI backend during a Vivado xsim run. Sibling-backend sources are purged from a reused Vivado project before loading the selected one (guarded by VIVADO_VERSION, since get_files/remove_files are Vivado-only and GHDL has no persistent project to clean), so switching backends no longer requires "make clean". On Vivado <= 2024.1 the bundled gcc-9.3.0 xsc link step uses its own binutils via -B and does not search the host multiarch lib dir, so the link fails with 'cannot find crti.o / -lzmq / -lm'. Point the startfile (-B) and library (-L) search at the active gcc's lib dir, derived portably via 'gcc -print-file-name=crti.o' (/usr/lib/x86_64-linux-gnu on Debian/Ubuntu, /usr/lib64 on RHEL). Harmless on Vivado >= 2024.2, whose xsc already resolves these. Add axi/simlink/README.md describing the three interchangeable backends and how to run the xsim co-sim in the GUI, linked from axi/README.md. Ignore the xsim/xsc build outputs in .gitignore and tidy a few stale cocotb test comments (JESD204B RX/TX register tests and the AXI Stream batcher test). Verified end-to-end against Vivado 2025.2 + the rogue_v6.13.0 conda env: the RogueTcpStream loopback demo exchanges PRBS frames through the DPI and reports rxErrors == 0 (byte-correct marshalling).

bengineerd

Requesting changes for per-instance DPI state and runnable usage documentation. The focused static checks and GHDL analysis are otherwise clean.

Approach A: a VHDL testbench drives the eight-instance DPI topology while eight independent rogue_tcp_peer.py subprocesses provide connected-and- draining peers, proving isolated live ZeroMQ traffic through the real xsim DPI boundary (not just elaboration). Positive + foreign-tag-rejection isolation checks; Option B fixed settle delay for readiness. Placed under docs/plans/<task-name>/ per AGENTS.md task-tracking convention, as a sibling to docs/plans/xsim-cosim-multi-instance/. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Eight bite-sized TDD tasks: per-tag peer helpers (unit-tested without Vivado), backward-compatible --tag threading, shared xsim helper refactor, then the traffic top + orchestration built up one model type at a time (Stream -> Memory -> SideBand) validated under real xsim, settle-delay tuning, and full regression + handoff notes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>